--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
docs/en/rns-link-api.md v4.8.1 (f6cc7b83) Text, 7.04 KB
RNS Link API
MeshChatX exposes a generic Reticulum Link transport on the main WebSocket (T383838/ws). External apps and plugins can open links, run request/response exchanges, send packets, and tear links down without going through NomadNet helpers.
When to use it
T282828
Your app or plugin needs a live RNS Link
|
--> Not NomadNet page browsing
--> Not LXMF messaging
|
--> Use rns.link.* over /ws
or plugin managers rnsLink.*
Address peers by destination hash and aspect. Do not invent IP or hostname shortcuts.
Auth
When password auth is enabled, every T383838rns.link.* client message needs an authenticated session. Same rule as other WebSocket mutators.
Link lifecycle
T282828
Client sends rns.link.open
|
--> MeshChatX finds or opens path to destination
|
--> Link cached under (aspect, destination_hash)
|
--> Optional auto_identify
|
--> success / failure reply on same type + request_id
|
+--> rns.link.request / rns.link.send on the cached link
|
+--> rns.link.close tears down and uncaches
|
+--> disconnect cancels in-flight open / request for that client
Cache notes:
• Key is T383838(aspect, destination_hash)
• Cap is 64 active links
• Idle links expire after about 30 minutes
• Repeated request failures recycle the cached link so the next call re-opens
Client to server
All messages need a unique T383838request_id so replies can be matched.
┌───────────────────┬───────────────────────────────────────────────────┬───────────────────┬──────┐
│ `BT383838`Fdddtype`f`b │ Required fields │ Optional │ Beh… │
├───────────────────┼───────────────────────────────────────────────────┼───────────────────┼──────┤
│ T383838rns.link.open │ T383838destination_hash, T383838aspect, T383838request_id │ T383838auto_identify │ Ope… │
│ T383838rns.link.identify │ T383838destination_hash, T383838aspect, T383838request_id │ │ Cal… │
│ T383838rns.link.request │ T383838destination_hash, T383838aspect, T383838path, T383838request_id │ T383838data_b64, T383838timeout │ Ens… │
│ T383838rns.link.send │ T383838destination_hash, T383838aspect, T383838payload_b64, T383838request_id │ │ Sen… │
│ T383838rns.link.close │ T383838destination_hash, T383838aspect, T383838request_id │ │ Tea… │
└───────────────────┴───────────────────────────────────────────────────┴───────────────────┴──────┘
Field details:
• T383838destination_hash: hex string of the peer destination
• T383838aspect: dot-separated RNS app name + sub-aspects, for example T383838microrn.mgmt
• T383838data_b64 / T383838payload_b64 / reply T383838body_b64: msgpack payloads, base64-encoded
• T383838path: request path string on the remote link endpoint
• T383838timeout: seconds for the request wait
Example open:
T282828
Tb4b4b4{
Tff7b72"type"Tb4b4b4: Ta5d6ff"rns.link.open"Tb4b4b4,
Tff7b72"destination_hash"Tb4b4b4: Ta5d6ff"aabbccddeeff00112233445566778899aabbccdd"Tb4b4b4,
Tff7b72"aspect"Tb4b4b4: Ta5d6ff"microrn.mgmt"Tb4b4b4,
Tff7b72"request_id"Tb4b4b4: Ta5d6ff"req-1"Tb4b4b4,
Tff7b72"auto_identify"Tb4b4b4: Tff7b72true
Tb4b4b4}
Example request:
T282828
Tb4b4b4{
Tff7b72"type"Tb4b4b4: Ta5d6ff"rns.link.request"Tb4b4b4,
Tff7b72"destination_hash"Tb4b4b4: Ta5d6ff"aabbccddeeff00112233445566778899aabbccdd"Tb4b4b4,
Tff7b72"aspect"Tb4b4b4: Ta5d6ff"microrn.mgmt"Tb4b4b4,
Tff7b72"path"Tb4b4b4: Ta5d6ff"/status"Tb4b4b4,
Tff7b72"request_id"Tb4b4b4: Ta5d6ff"req-2"Tb4b4b4,
Tff7b72"data_b64"Tb4b4b4: Tff7b72nullTb4b4b4,
Tff7b72"timeout"Tb4b4b4: T79c0ff15
Tb4b4b4}
Server to client
Per-T383838request_id replies reuse the same T383838type with a T383838status:
┌──────────┬──────────────────────────────────────────────┐
│ `BT383838`Fdddstatus`f`b │ Meaning │
├──────────┼──────────────────────────────────────────────┤
│ T383838phase │ Progress step while opening or requesting │
│ T383838progress │ Additional progress detail when available │
│ T383838success │ Operation finished │
│ T383838failure │ Operation failed (includes an error message) │
└──────────┴──────────────────────────────────────────────┘
Broadcast events (not tied to one T383838request_id):
┌────────────────┬─────────────────┬──────────────────────┐
│ `BT383838`Fdddtype`f`b │ `BT383838`Fdddevent`f`b │ Notes │
├────────────────┼─────────────────┼──────────────────────┤
│ T383838rns.link.event │ T383838packet_received │ Includes T383838payload_b64 │
│ T383838rns.link.event │ T383838link_closed │ Cached link removed │
└────────────────┴─────────────────┴──────────────────────┘
T282828
Inbound packet on a cached link
|
--> Broadcast rns.link.event / packet_received
|
Link torn down or evicted
|
--> Broadcast rns.link.event / link_closed
Plugins
Plugins call the same transport through HTTP invoke instead of speaking WebSocket types directly.
T282828
Plugin Worker
|
--> POST /api/v1/plugins/{id}/invoke
method: "callManager"
|
--> PluginManager checks granted managers
|
--> RnsLinkManager open / identify / request / send / close
Declare managers in T383838plugin.json:
┌──────────────────┬─────────────────────────┐
│ Manager │ Maps to │
├──────────────────┼─────────────────────────┤
│ T383838rnsLink.open │ Open or reuse link │
│ T383838rnsLink.identify │ Identify on cached link │
│ T383838rnsLink.request │ Request/response │
│ T383838rnsLink.send │ Raw packet send │
│ T383838rnsLink.close │ Teardown │
└──────────────────┴─────────────────────────┘
Subscribe to async traffic with:
T282828
Tb4b4b4{
Tff7b72"permissions"Tb4b4b4: Tb4b4b4{
Tff7b72"hooks"Tb4b4b4: Tb4b4b4[Ta5d6ff"rns.link.event"Tb4b4b4],
Tff7b72"managers"Tb4b4b4: Tb4b4b4[Ta5d6ff"rnsLink.open"Tb4b4b4, Ta5d6ff"rnsLink.identify"Tb4b4b4, Ta5d6ff"rnsLink.request"Tb4b4b4, Ta5d6ff"rnsLink.send"Tb4b4b4, Ta5d6ff"rnsLink.close"Tb4b4b4],
Tff7b72"storage"Tb4b4b4: Ta5d6ff"isolated"Tb4b4b4,
Tff7b72"network"Tb4b4b4: Ta5d6ff"none"
Tb4b4b4}
Tb4b4b4}
Hook delivery:
T282828
RnsLinkManager event
|
--> PluginManager.dispatch_hook("rns.link.event", …)
|
--> WebSocket plugin.event to the UI
|
--> Plugin Worker on_hook / event handler
External app pattern
T282828
Connect to MeshChatX /ws (auth cookie / session as required)
|
--> Send rns.link.open with request_id
|
--> Wait for matching success
|
--> Send rns.link.request or rns.link.send
|
--> Listen for rns.link.event broadcasts
|
--> Send rns.link.close when finished
Keep one T383838request_id per outstanding call. Cancel or ignore replies after you disconnect. MeshChatX cancels in-flight open/request work for that WebSocket client on disconnect.
Limits and failure behaviour
• Missing path or unreachable peer returns T383838failure on the open/request reply
• After repeated request failures on one cached link, MeshChatX recycles that link
• Idle unused links are swept after about 30 minutes
• Over-cap eviction drops the oldest unused links first
Implementation map
T282828
/ws rns.link.*
|
--> meshchat.py WebSocket dispatch + per-client task tracking
|
--> rns_link_manager.py cache, open, identify, request, send, close
|
--> plugin_manager.py capability wrappers + hook fan-out
See also
• Plugins for install, grants, and invoke flow
• Architecture and design for WebSocket and plugin runtime overview
• Identities, privacy, and security for auth and session rules
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────